接入文档

SDK接入指南

一、原生平台

1.1 iOS

1.1.1 工程配置

①添加framework文件 ②设置framework搜索路径 ③设置header搜索路径
a64923c6b011c93fb2e13e554a72c690.png 8b349025cd6612eaf1fae4c9e96a1313.png即存放netshield.framework的本地目录 91c69e1d61fc7ed4d3c441d3286f9bc2.png 即netshield.framework的全路径追加"/Headers"

1.1.2 接口说明

头文件LibNetshield.h

方法 说明
+ (void)startService:key:completionHandler: 启动防护服务
pid-项目ID
key-授权密钥
completionHandler-启动回调函数,详见示例代码
+ (int)getLocalhostPort: 根据规则名获取本地端口
+ (void)stopService 停止防护服务,释放资源

1.1.3 示例代码

// 引入头文件
#import <LibNetshield.h>

// 启动防护服务
[LibNetshield startService:@"123" 
                        key:@"12345678901234567890" 
          completionHandler:^(BOOL success, NSString *errMsg, NSString *clientIP) {
    // startResult SDK是否成功启动 YES-启动成功 NO-启动失败
    // errMessage  启动失败时用于获取失败原因,启动成功时可忽略
    // clientIP    启动成功时为客户端真实IP,启动失败为空
    if (startResult) {
        NSLog(@"SDK started success,clientIP:%@", clientIP);
    } else {
        NSLog(@"SDK started failed");
    }
}];

// 根据规则名获取本地端口
int localPort = [LibNetshield getLocalhostPort:@"test;10001"];
// 通过本地端口访问真实后端服务
NSString *url = [NSString stringWithFormat:@"http://127.0.0.1:%d", localPort];

// 停止防护服务,释放资源
[LibNetshield stopService];
// 引入头文件
#import <LibNetshield.h>

// 启动防护服务
[LibNetshield startService:@"123" 
                        key:@"12345678901234567890" 
          completionHandler:^(BOOL success, NSString *errMsg, NSString *clientIP) {
    // startResult SDK是否成功启动 YES-启动成功 NO-启动失败
    // errMessage  启动失败时用于获取失败原因,启动成功时可忽略
    // clientIP    启动成功时为客户端真实IP,启动失败为空
    if (startResult) {
        NSLog(@"SDK started success,clientIP:%@", clientIP);
    } else {
        NSLog(@"SDK started failed");
    }
}];

// 根据规则名获取本地端口
int localPort = [LibNetshield getLocalhostPort:@"test;10001"];
// 通过本地端口访问真实后端服务
NSString *url = [NSString stringWithFormat:@"http://127.0.0.1:%d", localPort];

// 停止防护服务,释放资源
[LibNetshield stopService];

1.2 macOS平台

1.2.1 工程配置

①添加dylib文件 ②设置dylib链接搜索路径
53115164fc25a346700539774b1cbabf.png 044a0fe6f062ff9a05fdcf58ee104c7d.png即存放libnetshield.dylib的本地目录

1.2.2 接口说明

方法 说明
void startNetshieldService(const char *pid, const char *key, void (*completionHandler)(int, const char *, const char *)) 启动防护服务
pid-项目ID
key-授权密钥
completionHandler-启动回调函数,详见示例代码
int getLocalhostPort(const char *) 根据规则名获取本地端口
void stopNetshieldService() 停止防护服务,释放资源

1.2.3 示例代码

以下代码为c++和objc混编,需要将接入源码的 .m 后缀修改为 .mm

①添加extern函数声明

#ifdef __cplusplus
extern "C" {
#endif
extern void startNetshieldService(const char *, const char *, void (*)(int, const char *, const char *));
extern int getLocalhostPort(const char *);
extern void stopNetshieldService();
#ifdef __cplusplus
}
#endif
#ifdef __cplusplus
extern "C" {
#endif
extern void startNetshieldService(const char *, const char *, void (*)(int, const char *, const char *));
extern int getLocalhostPort(const char *);
extern void stopNetshieldService();
#ifdef __cplusplus
}
#endif

②调用接口

// 启动防护服务
NSString *pid = @"123";
NSString *key = @"12345678901234567890";
startNetshieldService([pid UTF8String], [key UTF8String], [](int startResult, const char *errMessage, const char *clientIP){
    // startResult SDK是否成功启动 0-启动成功 -1-启动失败
    // errMessage  启动失败时用于获取失败原因,启动成功时可忽略
    // clientIP    启动成功时为客户端真实IP,启动失败为空
    if (0 == startResult) {
        NSLog(@"SDK started success,clientIP:%s", clientIP);
    } else {
        NSLog(@"SDK started failed,err:%s", errMessage);
    }
});

// 根据规则名获取本地端口
int localhostPort = getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
NSString *localhostUrl = [NSString stringWithFormat:@"http://127.0.0.1:%d", localhostPort];

// 停止防护服务,释放资源
stopNetshieldService();
// 启动防护服务
NSString *pid = @"123";
NSString *key = @"12345678901234567890";
startNetshieldService([pid UTF8String], [key UTF8String], [](int startResult, const char *errMessage, const char *clientIP){
    // startResult SDK是否成功启动 0-启动成功 -1-启动失败
    // errMessage  启动失败时用于获取失败原因,启动成功时可忽略
    // clientIP    启动成功时为客户端真实IP,启动失败为空
    if (0 == startResult) {
        NSLog(@"SDK started success,clientIP:%s", clientIP);
    } else {
        NSLog(@"SDK started failed,err:%s", errMessage);
    }
});

// 根据规则名获取本地端口
int localhostPort = getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
NSString *localhostUrl = [NSString stringWithFormat:@"http://127.0.0.1:%d", localhostPort];

// 停止防护服务,释放资源
stopNetshieldService();

1.3 Android平台

1.3.1 工程配置

①app/build.gradle添加aar路径 ②调整minSdkVersion为21或以上
1fb309bcf29214a87739d98a00eed141.png dir中的目录即即存放netshield.aar的本地目录,可以为全路径 8bd77e77f2d9ee3bc33cc86bbb9bf2c0.png

1.3.2 接口说明

类文件com.netshield.Netshield

方法 说明
static int startService(String pid, String key) 启动防护服务
pid-项目ID
key-授权密钥
static String getClientIP() 获取客户端真实IP,需要在SDK启动成功后调用
static int getLocalhostPort(String rule) 根据规则名获取本地端口
static void stopService() 停止防护服务,释放资源

1.3.2 示例代码

// 启动防护服务
int code = Netshield.startService("123", "12345678901234567890");
if (code == 0) {
    // 获取真实的客户端IP
    String clientIP = Netshield.getClientIP();
    Log.d("SDK", "Client IP: " + clientIP);
} else {
    Log.e("SDK", "SDK初始化失败");
}

// 根据规则名获取本地端口
int localPort = Netshield.getLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
String url = String.format("http://127.0.0.1:%d", localPort);

// 停止防护服务,释放资源
stopService();
// 启动防护服务
int code = Netshield.startService("123", "12345678901234567890");
if (code == 0) {
    // 获取真实的客户端IP
    String clientIP = Netshield.getClientIP();
    Log.d("SDK", "Client IP: " + clientIP);
} else {
    Log.e("SDK", "SDK初始化失败");
}

// 根据规则名获取本地端口
int localPort = Netshield.getLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
String url = String.format("http://127.0.0.1:%d", localPort);

// 停止防护服务,释放资源
stopService();

1.4 Windows平台

1.4.1 工程配置

将netshield.dll放置到exe同级目录

1.4.2 接口说明

方法 说明
int startNetshieldService(const char *pid, const char *key) 启动防护服务
pid-项目ID
key-授权密钥
const char *getClientIP() 获取客户端真实IP,需要在SDK启动成功后调用
int getLocalhostPort(const char *rule) 根据规则名获取本地端口
void stopNetshieldService() 停止防护服务,释放资源

1.4.3 示例代码

① 动态加载DLL

HMODULE netshieldDll                                      = LoadLibrary(L"netshield.dll");
auto (*startNetshieldService)(const char *, const char *) = reinterpret_cast<int(__cdecl *)(const char *, const char *)>(GetProcAddress(netshieldDll, "startNetshieldService"));
auto (*getClientIP)()                                     = reinterpret_cast<const char *(__cdecl *)()>(GetProcAddress(netshieldDll, "getClientIP"));
auto (*getLocalhostPort)(const char *)                    = reinterpret_cast<int(__cdecl *)(const char *)>(GetProcAddress(netshieldDll, "getLocalhostPort"));
auto (*stopNetshieldService)()                            = reinterpret_cast<void(__cdecl *)()>(GetProcAddress(netshieldDll, "stopNetshieldService"));
HMODULE netshieldDll                                      = LoadLibrary(L"netshield.dll");
auto (*startNetshieldService)(const char *, const char *) = reinterpret_cast<int(__cdecl *)(const char *, const char *)>(GetProcAddress(netshieldDll, "startNetshieldService"));
auto (*getClientIP)()                                     = reinterpret_cast<const char *(__cdecl *)()>(GetProcAddress(netshieldDll, "getClientIP"));
auto (*getLocalhostPort)(const char *)                    = reinterpret_cast<int(__cdecl *)(const char *)>(GetProcAddress(netshieldDll, "getLocalhostPort"));
auto (*stopNetshieldService)()                            = reinterpret_cast<void(__cdecl *)()>(GetProcAddress(netshieldDll, "stopNetshieldService"));

② 调用接口

// 启动防护服务
int rc = startNetshieldService("123", "12345678901234567890");
if (rc == 0) {
    // 获取真实的客户端IP
    const char* clientIP = getClientIP();
    printf("Client IP: %s\n", clientIP);
} else {
    printf("SDK初始化失败\n");
}

// 根据规则名获取本地端口
int localPort = getLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
char url[1024];
snprintf(url, sizeof(url), "http://127.0.0.1:%d", localPort);

// 停止防护服务,释放资源
// 如果遇到进程无法退出,需要在main函数结束前调用该函数
stopNetshieldService();
// 启动防护服务
int rc = startNetshieldService("123", "12345678901234567890");
if (rc == 0) {
    // 获取真实的客户端IP
    const char* clientIP = getClientIP();
    printf("Client IP: %s\n", clientIP);
} else {
    printf("SDK初始化失败\n");
}

// 根据规则名获取本地端口
int localPort = getLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
char url[1024];
snprintf(url, sizeof(url), "http://127.0.0.1:%d", localPort);

// 停止防护服务,释放资源
// 如果遇到进程无法退出,需要在main函数结束前调用该函数
stopNetshieldService();

二、Unity平台

1、按下图目录结构拷贝SDK文件

├── Assets
│   ├── Plugins
│   │   ├── Netshield
│   │   │   ├── Android
│   │   │   │   ├── netshield-release.aar
│   │   │   ├── Windows
│   │   │   │   ├── netshield.dll
│   │   │   ├── iOS
│   │   │   │   ├── netshield.framework
│   │   │   ├── macOS
│   │   │   │   ├── libnetshield.dylib
│   └── Scripts
│   ├── Netshield
│   │   ├── INetshieldInterface.cs
│   │   ├── Netshield.cs
│   │   ├── impl
│   │   │   ├── Netshield4Android.cs
│   │   │   ├── Netshield4OSX.cs
│   │   │   ├── Netshield4Others.cs
│   │   │   ├── Netshield4Windows.cs

Netshield.zip

2、接口说明

方法 说明
Netshield4Unity.GetInstance() 获取Netshield4Unity单例对象
void StartService(string pid, string key, CompletionHandler completionHandler) 启动防护服务
pid-项目ID
key-授权密钥
completionHandler-启动回调函数,详见示例代码
void StopService() 停止防护服务,释放资源
int GetLocalhostPort(string rule) 根据规则名获取本地端口

3、示例代码

// 启动防护服务
Netshield4Unity.GetInstance().StartService("123", "12345678901234567890", (result, msg, ip) => {
    // result SDK是否成功启动 0-启动成功 -1-启动失败
    // msg   启动失败时用于获取失败原因,启动成功时可忽略
    // ip    启动成功时为客户端真实IP,启动失败为空
    Debug.Log(result == 0 ? $"Success: {ip}" : $"Error: {msg}");
});

// 根据规则名获取本地端口
int localPort = Netshield.Netshield4Unity.GetInstance().GetLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
var url = "http://127.0.0.1:" + localPort;

// 停止防护
Netshield4Unity.GetInstance().StopService();
// 启动防护服务
Netshield4Unity.GetInstance().StartService("123", "12345678901234567890", (result, msg, ip) => {
    // result SDK是否成功启动 0-启动成功 -1-启动失败
    // msg   启动失败时用于获取失败原因,启动成功时可忽略
    // ip    启动成功时为客户端真实IP,启动失败为空
    Debug.Log(result == 0 ? $"Success: {ip}" : $"Error: {msg}");
});

// 根据规则名获取本地端口
int localPort = Netshield.Netshield4Unity.GetInstance().GetLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
var url = "http://127.0.0.1:" + localPort;

// 停止防护
Netshield4Unity.GetInstance().StopService();

三、Cocos Creator

3.1 拷贝js接口文件到脚本目录

Netshield.js

3.2 拷贝库文件到各平台

3.2.1 iOS和mac

①将SDK添加到工程中 ②选择同时添加到iOS和macOS中
d515b8406ec3fd393b1b83d7db1b46d8.png 8133a84ae1d283b038b055964aa3cca4.png
③将桥接文件添加到Classes目录 ④检查结果
348bb78ac10a78f718f71b1b8adf8921.png 8a1e0b19f2ea8babf80bda26340d8996.png
⑤iOS-添加framework文件 ⑥iOS-设置framework搜索路径
2794830befa1ec31445268084bc76d92.png a43f3ba9ec467cbfd44e6af438a00e0a.png${SRCROOT}/../../../../../netshield/ios_mac/ios
⑦mac-添加dylib文件 ⑧mac-设置dylib链接搜索路径
590efb7554fe50dafe2f9acb21de72ce.png 0796e533dcd0c576671df0be2f0888e5.png${SRCROOT}/../../../../../netshield/ios_mac/mac
⑨mac-设置dylib运行搜索路径
67524ce6448941b600a09e8736561b79.png@executable_path/../Frameworks

3.2.2 Android

①app/build.gradle添加aar路径 ②调整minSdkVersion为21或以上
1fb309bcf29214a87739d98a00eed141.png implementation fileTree(dir: '../../../../../../netshield/android', include: ['*.aar'] 8bd77e77f2d9ee3bc33cc86bbb9bf2c0.png

3.2.3 Windows

①将代码文件添加到工程中 ②在jsb_module_register.cpp中注册
b47ba7372480f2ec762da3eba46d10e6.png 1ae27174987084c080800dd3961856c9.png
步骤②代码 ③将dll文件添加到工程中
#if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)    
#include "NetshieldBridge.hpp"
#endif

// 以下代码需要添加到jsb_register_all_modules函数中
#if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)
se->addRegisterCallback(register_netshield_bridge);
#endif
4be7abcf00f5d15fade9f1d7f82bf62a.png

3.3 调用接口

async onStartSDK() {
    // 启动防护服务
    console.log("启动SDK...");
    try {
        const result = await Netshield.start("123", "1231231231231231231231");
        if (result.startResult === 0) {
            // result.clientIP为真实的客户端IP
            console.log("SDK 启动成功,IP:" + result.clientIP);
        } else {
            console.log("SDK 启动失败:" + result.errorMessage);
        }
    } catch (error) {
        console.log("SDK 启动异常:" + error);
    }
},

onRequestPage() {
    // 根据规则名获取本地端口
    const localhostPort = Netshield.getLocalhostPort("240.0.0.2;80");
    // 通过本地端口访问真实后端服务
    let url = "http://127.0.0.1:" + this.localhostPort;
    console.log("访问页面: " + url);
}

onStopSDK() {
    console.log("停止SDK");
    Netshield.stop();
    console.log("SDK 已停止");
},
async onStartSDK() {
    // 启动防护服务
    console.log("启动SDK...");
    try {
        const result = await Netshield.start("123", "1231231231231231231231");
        if (result.startResult === 0) {
            // result.clientIP为真实的客户端IP
            console.log("SDK 启动成功,IP:" + result.clientIP);
        } else {
            console.log("SDK 启动失败:" + result.errorMessage);
        }
    } catch (error) {
        console.log("SDK 启动异常:" + error);
    }
},

onRequestPage() {
    // 根据规则名获取本地端口
    const localhostPort = Netshield.getLocalhostPort("240.0.0.2;80");
    // 通过本地端口访问真实后端服务
    let url = "http://127.0.0.1:" + this.localhostPort;
    console.log("访问页面: " + url);
}

onStopSDK() {
    console.log("停止SDK");
    Netshield.stop();
    console.log("SDK 已停止");
},

四、Flutter

SDK以flutter plugin的形式提供

4.1 添加依赖

通过本地路径的方式引入plugin

dependencies:
  netshield4flutter:
    path: ../path/to/your/netshield4flutter
dependencies:
  netshield4flutter:
    path: ../path/to/your/netshield4flutter

4.2 接入代码(详细用法请参考plugin example)

import 'package:netshield4flutter/netshield4flutter.dart';

final _netshield4flutterPlugin = Netshield4flutter();
try {
    // 启动防护服务
    final startResult = await _netshield4flutterPlugin.startService('123', '12345678901234567890');
    if (startResult.isSuccess) {
    	print("SDK 已启动");
        // startResult.clientIP为真实的客户端IP
    	print("Client IP: ${startResult.clientIP}");
    } else {
    	print("SDK 启动失败: ${startResult.errorMessage}");
    }
} on PlatformException {
    print("SDK 启动失败");
}

int localhostPort = -1;
try {
    // 根据规则名获取本地端口
    localhostPort = await _netshield4flutterPlugin.getLocalhostPort("240.0.0.2;80");
    // 通过本地端口访问真实后端服务
    String url = "http://127.0.0.1:$localhostPort";
} on PlatformException {
    print("无法获取本地端口");
}

// 可选代码,应用退出时可自动关闭
try {
    // 关闭防护服务
    await _netshield4flutterPlugin.stopService();
    print("SDK 已停止");
} on PlatformException {
    print("SDK 停止失败");
}
import 'package:netshield4flutter/netshield4flutter.dart';

final _netshield4flutterPlugin = Netshield4flutter();
try {
    // 启动防护服务
    final startResult = await _netshield4flutterPlugin.startService('123', '12345678901234567890');
    if (startResult.isSuccess) {
    	print("SDK 已启动");
        // startResult.clientIP为真实的客户端IP
    	print("Client IP: ${startResult.clientIP}");
    } else {
    	print("SDK 启动失败: ${startResult.errorMessage}");
    }
} on PlatformException {
    print("SDK 启动失败");
}

int localhostPort = -1;
try {
    // 根据规则名获取本地端口
    localhostPort = await _netshield4flutterPlugin.getLocalhostPort("240.0.0.2;80");
    // 通过本地端口访问真实后端服务
    String url = "http://127.0.0.1:$localhostPort";
} on PlatformException {
    print("无法获取本地端口");
}

// 可选代码,应用退出时可自动关闭
try {
    // 关闭防护服务
    await _netshield4flutterPlugin.stopService();
    print("SDK 已停止");
} on PlatformException {
    print("SDK 停止失败");
}

五、UniApp

5.1 uts插件

5.1.1 放置插件

将uts插件放到uni_modules目录下
d239a787bfdc02eac787bf210e418e74.png

5.1.2接入代码

import { startNetshieldService, stopNetshieldService, getLocalhostPort } from "@/uni_modules/dev-netshield";

export default {
    methods: {
        startSDK() {
            console.log("启动SDK");
            // 启动防护服务
            startNetshieldService("123", "1231231231231231231231", (res : Array<string>) => {
                if ("0" == res[0]) {
                    console.log("SDK启动成功");
                    // result[2]为真实的客户端IP
                    console.log("客户端真实IP:" + res[2]);
                } else {
                    console.log("SDK启动失败");
                    console.log("错误信息:" + res[1]);
                }
            });
        },
        browse() {
            // 根据规则名获取本地端口
            const localhostPort = getLocalhostPort("240.0.0.2;80");
            // 通过本地端口访问真实后端服务
            let url = "http://127.0.0.1:" + localhostPort;
            console.log("访问页面: " + url);
        },
        stopSDK() {
            console.log("关闭SDK");
            stopNetshieldService();
            console.log("SDK已关闭");
        }
    }
}
import { startNetshieldService, stopNetshieldService, getLocalhostPort } from "@/uni_modules/dev-netshield";

export default {
    methods: {
        startSDK() {
            console.log("启动SDK");
            // 启动防护服务
            startNetshieldService("123", "1231231231231231231231", (res : Array<string>) => {
                if ("0" == res[0]) {
                    console.log("SDK启动成功");
                    // result[2]为真实的客户端IP
                    console.log("客户端真实IP:" + res[2]);
                } else {
                    console.log("SDK启动失败");
                    console.log("错误信息:" + res[1]);
                }
            });
        },
        browse() {
            // 根据规则名获取本地端口
            const localhostPort = getLocalhostPort("240.0.0.2;80");
            // 通过本地端口访问真实后端服务
            let url = "http://127.0.0.1:" + localhostPort;
            console.log("访问页面: " + url);
        },
        stopSDK() {
            console.log("关闭SDK");
            stopNetshieldService();
            console.log("SDK已关闭");
        }
    }
}

5.2 原生插件

5.2.1 放置及启用插件

①将native插件放到nativeplugins目录下 ②在manifest.json中选择本地插件
768398eca1519b4112c4a28398f33db7.png 83600eb139ed60e7127dde4726f5437d.png

5.2.2 接入代码

const netshieldNativePlugin = uni.requireNativePlugin('netshieldNativePlugin');

export default {
    methods: {
        startSDK() {
            console.log("启动SDK");
            // 启动防护服务
            netshieldNativePlugin.startNetshieldService("123", "1231231231231231231231", (ret) => {
                if ("0" == ret.startResult) {
                    console.log("SDK启动成功");
                    // ret.clientIP为真实的客户端IP
                    console.log("clientIP:" + ret.clientIP);
                } else {
                    console.log("SDK启动失败");
                    console.log("errMessage:" + ret.errMessage);
                }
            });
        },
        browse() {
            // 根据规则名获取本地端口
            const localhostPort = netshieldNativePlugin.getLocalhostPort("240.0.0.2;80");
            // 通过本地端口访问真实后端服务
            let url = "http://127.0.0.1:" + localhostPort;
            console.log("访问页面: " + url);
        },
        stopSDK() {
            console.log("关闭SDK");
            netshieldNativePlugin.stopNetshieldService();
            console.log("SDK已关闭");
        }
    }
}
const netshieldNativePlugin = uni.requireNativePlugin('netshieldNativePlugin');

export default {
    methods: {
        startSDK() {
            console.log("启动SDK");
            // 启动防护服务
            netshieldNativePlugin.startNetshieldService("123", "1231231231231231231231", (ret) => {
                if ("0" == ret.startResult) {
                    console.log("SDK启动成功");
                    // ret.clientIP为真实的客户端IP
                    console.log("clientIP:" + ret.clientIP);
                } else {
                    console.log("SDK启动失败");
                    console.log("errMessage:" + ret.errMessage);
                }
            });
        },
        browse() {
            // 根据规则名获取本地端口
            const localhostPort = netshieldNativePlugin.getLocalhostPort("240.0.0.2;80");
            // 通过本地端口访问真实后端服务
            let url = "http://127.0.0.1:" + localhostPort;
            console.log("访问页面: " + url);
        },
        stopSDK() {
            console.log("关闭SDK");
            netshieldNativePlugin.stopNetshieldService();
            console.log("SDK已关闭");
        }
    }
}

六、注意事项

  1. 初始化时机:在应用启动后尽早调用初始化方法
  2. 错误处理
    • iOS/macOS通过completionHandler回调判断结果
    • 其他平台通过返回值判断(0=成功)
  3. 资源释放:退出时需调用stopNetshieldService方法释放资源
  4. 动态库依赖:Windows需正确部署netshield.dll,iOS和macOS平台的framework必须配置为Embed模式,否则会导致运行时崩溃

七、技术支持

商务合作与技术支持请联系telegram: youxidun